Programming Languages Suite

home *** CD-ROM | disk | FTP | other *** search

/ Programming Languages Suite / ProgramD2.iso / Languages / Masm V6.11 / README.TXT < prev next >

Wrap

Text File | 1993-09-29 | 28.0 KB | 700 lines

README.TXT File Release Notes for the Microsoft(R) MASM Professional Development System, Version 6.11 (C) Copyright 1993, Microsoft Corporation. All rights reserved. This document contains release notes for the Microsoft MASM Professional Development System, version 6.11. The information in this document and in the Microsoft Advisor (online help) is more up-to-date than that in the manuals. The printed documentation for MASM 6.11 has not changed from MASM 6.1. The MASM 6.11 installation disks provide several important files that include new or updated information for this release. They are: README.TXT =====> Contains documentation errata, system requirements, information and tips on using MASM 6.11, and known assembler bugs. PENTIUM.TXT ====> Contains .586 and .586P directives information, descriptions of the new Intel(R) Pentium(TM) instructions, and a table of Pentium timings for all instructions. CV.TXT =========> Contains release notes for Microsoft CodeView(TM). ERRMSG.TXT =====> Contains updated information on 32-bit Linker errors, ML error messages, and Microsoft DOSXNT MS-DOS Extender error messages. SAMPLES.TXT ====> Contains information about MASM samples for MS-DOS and Microsoft Windows 3.1. NTSAMPLE.TXT ===> Contains information about MASM samples for Microsoft Windows NT. SUPPORT.TXT ====> Contains updated Microsoft Product Support policies. ======================< README.TXT Table of Contents >===================== Part 1: Documentation Errata ---------------------------- Part 2: System Requirements --------------------------- Part 3: Tips for Using MASM 6.1x -------------------------------- - ALIAS directive - Assembling Files Generated by Compiler - Building 32-Bit Applications - 32-Bit Linking - GROUP Directive and Flat-Model Programming - Structure Packing Issues for Mixed Language Programming - /WIN32 Switch for H2INC - CD-ROM Not a Valid Target - CMP Instruction Encoding - Debugging MASM Applications under Visual C++, 32-Bit Edition, or Fortran PowerStation, 32-Bit Edition - .FPO Directive - INVOKE Command - LINK and System Resources - MOUSE.COM - MS-DOS and Windows NT File Compatibility - Multi-File Assembly with MASM.EXE - NMAKE and NMAKER - Response Files - SAMPLES.TXT and NTSAMPLE.TXT - Using Control-C to Halt Operation of MASM - Using MASM 6.x Structures - Visual C++ 1.0/Fortran PowerStation 1.0 Compatibility - Working with MASM 5.1 Code - Working With Microsoft BASIC Far Strings Part 4: Known Assembler Bugs ---------------------------- - Exiting from MS-DOS Critical Errors - Expression Order in High-Level Conditionals - Hexadecimal Constants - Initializing Nested Structures - Intersegment Near Jumps in Flat Model - Span-Dependent Expressions used in Macros - Span-Dependent Equates in Macros and EXTERNDEF ABS - Span-Dependent Text Equates - STRUCT and RECORD Initialization - Using The /link /nologo Command Line Options ====================< Part 1: Documentation Errata >======================= Environment and Tools, Page xxiii: Microsoft Support Services ------------------------------------------------------------- Microsoft Support Services information has been updated. See SUPPORT.TXT, in the directory in which you installed MASM, for the most current Microsoft support information and policies. Environment and Tools, Page 582: LIB Command Line Sample -------------------------------------------------------- The following example, as it appears on page 582, is incorrect: LIB FIRST +SECOND, , THIRD It should instead read: LIB THIRD +FIRST +SECOND Environment and Tools, Page 649, 651: _syscall and __syscall ------------------------------------------------------------ The H2INC documentation on pages 649 and 651 lists _syscall and __syscall as C keywords recognized by H2INC. These are not recognized, and should be removed. Environment and Tools, Page 819: Error Message A2156 ---------------------------------------------------- The value range given for the first parameter of the PAGE directive is incorrect; "...either 0 or a value in the range of 10-255" should read "...either 0 or a value in the range of 14-255." Reference, Page 12: ML Command-line Options /Cu and /Cx ------------------------------------------------------- /Cu is not the default command-line option, but is indicated as such in the MASM 6.1 Reference. Instead, /Cx should be indicated as the default. Reference, Page 98: LEA is no longer optimized ---------------------------------------------- The MASM 6.1 Reference indicates that the LEA instruction is encoded as a MOV when the source operand is a direct memory address. In response to programmer requests, MASM 6.1x no longer performs this optimization automatically. The optimization can be performed by using the OPATTR operator, as shown in the following macro: MOVLEA MACRO Dest, Symbol IF (OPATTR(Symbol)) AND 08h MOV Dest, OFFSET Symbol ELSE LEA Dest, Symbol ENDIF ENDM Programmer's Guide, Page 156: Using an Emulator Library ------------------------------------------------------- The sample code demonstrating floating-point instructions served by an emulator contains the directive .STARTUP. This directive should be removed. Programmer's Guide, Page 202: User-Defined Epilogues & Prologues ---------------------------------------------------------------- The documentation for user-defined epilogue and prologue code reads "Your macro function must return the parmbytes parameter." It should read "...the localbytes parameter." Programmer's Guide, Page 323: The C++/MASM Interface ---------------------------------------------------- The second sentence in the third paragraph reads: "The linkage specification applies only to called routines, not to external variables." It should read "The linkage specification applies to called routines and external variables." The last sentence in the same paragraph should be removed. Help for Runtime Error R6921 ---------------------------- The online help for runtime error R6921 reads "...Possibly the CONFIG.SYS file contained a line such as DEVICE=C:\OS\MM386.EXE..." The file name should read "C:\DOS\EMM386.EXE". =================< Part 2: MASM 6.11 System Requirements >================= The following are system requirements for Microsoft MASM 6.11: - Personal computer using a 386 or higher processor running MS-DOS version 3.3 or later, Windows version 3.1 or later, or Windows NT version 3.1 or later. - 4 MB of available memory. - Hard disk with 10 MB available space. - One 3.5" high-density (1.44 MB) disk drive (3.5" low-density (720K) or 5.25" high-density (1.2 MB) disks available separately with coupon enclosed). To target Windows 3.1, you need one of the following: - Microsoft Windows Software Development Kit (SDK) 3.1. - Microsoft Visual C++ Development System, Standard or Professional Edition. To target Windows NT, you need one of the following: - Microsoft Windows NT Software Development Kit (SDK). - Microsoft Visual C++ Development System, 32-Bit Edition. ====================< Part 3: Tips for Using MASM 6.11 >=================== ALIAS directive --------------- The ALIAS directive is not included in the printed documentation for MASM 6.11. The ALIAS directive can be used for creating libraries that allow the linker (LINK) to map an old function to a new function. Syntax: ALIAS <alias> = <actual-name> where alias is the alternate or alias name, and actual-name is the actual name of the function or procedure. The angle brackets are required. The ALIAS directive should be used with LINK 5.3 or later and LIB 3.2 or later. At this time, ALIAS functions only with the 16-bit linker. Assembling Files Generated by Compilers ------------------------------------------ Many compilers support assembly-language output. If you experience difficulty assembling the output of such compilers, you may need to assemble using the /Zm option. In some cases (for instance, if the compiler inserts nondelimited comments or page numbers) it may be necessary to edit the assembly-language output by hand. Building 32-bit Applications ---------------------------- Following are a number of items you should keep in mind when building 32-bit applications with MASM 6.11. Examples of how to create 32-bit applications can be found in the \SAMPLES\NTSAMPLE subdirectory of the directory in which you installed MASM. 32-bit Linking -------------- When you are creating a 32-bit application, you must link separately with a 32-bit linker. To prepare your object files for 32-bit linking, assemble using the following switches: - /c (assembles without linking) - /coff (causes object files to be created in Windows NT- compatible common object file format) After assembling, link with your 32-bit linker. Refer to the documentation included with your particular 32-bit linker for specific information and instructions. In addition, the sample NT applications in \SAMPLES\NTSAMPLE demonstrate the use of /c, /coff, and a 32-bit linker. GROUP Directive and Flat-Model Programming ------------------------------------------ The GROUP directive has no effect when used in 32-bit flat-model programming. It is recommended that you not use the GROUP directive when programming in flat model. Structure Packing Issues for Mixed Language Programming ------------------------------------------------------- Microsoft MASM uses /Zp1 as it's default setting for structure packing; this means that structures are not packed. Other languages may use other default settings for packing. For example, Microsoft C/C++ compilers prior to Visual C++ 32-bit edition use /Zp2; Visual C++ 32-bit edition uses /Zp8 as the default. Modules built using different structure packing may not be able to share structure data items, so care must be taken when using structures in mixed language programs. The packing size is a maximum, not a fixed, packing value. This means that a member must have a size equal to or larger than the packing limit before any packing is done. In many cases, using /Zp4 on assembly modules will allow them to work with other modules compiled with /Zp8 if none of the members have a size larger than 4 bytes. Doubles, long doubles, and member structures larger than 4 bytes will cause problems. If a structure contains members larger than 4 bytes you will need to pack the structure yourself by adding "dummy" data items. /WIN32 Switch for H2INC ----------------------- Use the /WIN32 switch with H2INC to convert C header files to NT-compatible MASM include files. When you use the /WIN32 switch, C int data types are converted to the 4-byte assembler equivalent DWORD (signed int data types are converted to SDWORD). Without the /WIN32 switch, H2INC converts int data types to 2-byte WORD (and signed int data types to SWORD). CD-ROM Not a Valid Target ------------------------- A CD-ROM drive is not a valid installation target for MASM 6.11. CMP Instruction Encoding ------------------------ MASM 6.1x uses a different encoding for the CMP <reg8>,<reg8> instruction than MASM 6.0 did. There is no difference in length or processor timing. Debugging MASM Applications under Visual C++, 32-bit Edition, or Fortran PowerStation, 32-bit Edition ------------------------------------------------------------- When debugging a pure MASM application under the 32-bit editions of Visual C++ or Fortran PowerStation, you must link in the library file (.LIB) provided with these high-level languages (LIBC.LIB in Visual C++, LIBF.LIB with Fortran PowerStation), instead of the one included with MASM 6.11. If you do not use the .LIB file included in the high-level language, you will receive an "Access Violation" error message when you attempt to run a MASM application in either the 32-bit Visual C++ or 32-bit Fortran PowerStation integrated development environment. .FPO Directive -------------- The .FPO directive controls the emission of debug records to the .debug$F segment or section. This directive was originally included with MASM386 and is not supported by MASM 6.11. If you are using both MASM 6.11 and MASM386, the following allows you to continue to implement the .FPO directive: IF @version LT 600 .FPO ENDIF INVOKE Command -------------- The MASM 6.x INVOKE command does not support transferring control between 16-bit and 32-bit code segments. When the assembler encounters an INVOKE command in a 16-bit segment, it assumes that the procedure being invoked is also in a 16-bit segment; if the assembler encounters an INVOKE in a 32-bit segment, it assumes that the invoked procedure is also in a 32-bit segment. To avoid this problem, push the necessary parameters on the stack and make the appropriate call instead of using INVOKE. LINK and System Resources ------------------------ You may encounter the following error message when running LINK on Windows 3.1: System resource exhausted. Abort, Retry, Fail? This may occur because LINK opens a large number of files, and the buffer for SHARE may have been exceeded. To fix this problem, edit your AUTOEXEC.BAT, setting the following values for SHARE: /L:500 /F:4096 MOUSE.COM --------- Microsoft Mouse Driver (MOUSE.COM) Version 8.20a is included with MASM 6.11. If you have a later version of the Microsoft Mouse installed on your system, it is recommended you use it instead of the Mouse Driver included with MASM 6.11. MS-DOS and Windows NT File Compatibility ---------------------------------------- Files installed on the Microsoft Windows NT File System (NTFS) are accessible only on Microsoft Windows NT. Files installed on the MS-DOS File System (FAT) are accessible on MS-DOS, Microsoft Windows, or Microsoft Windows NT. Multi-File Assembly with MASM.EXE --------------------------------- When assembling multiple files with MASM.EXE, you must terminate the command-line with a semi-colon or a comma (for example, MASM *.asm;). Failure to do this may cause the program to appear to hang if you are running Microsoft NT. If this does occur, you can terminate the program with Ctrl+C. NMAKE and NMAKER ---------------- MASM 6.11 includes two versions of the NMAKE project management utility. NMAKER.EXE is a real-mode version of the utility. NMAKE.EXE is a driver program which first loads the MS-DOS extender DOSXNT into memory, and then runs NMAKER.EXE. Using the NMAKE.EXE driver will result in faster build times. Some development tools from other manufacturers may be incompatible with NMAKE.EXE. If you encounter incompatibilities, use NMAKER.EXE instead. Response Files -------------- Information on response files is not included in the MASM 6.1 manuals; however, this information can be found in "ML Command Line Options" in Online help. SAMPLES.TXT and NTSAMPLE.TXT ---------------------------- SAMPLES.TXT contains information about the MASM samples for MS-DOS/Windows; NTSAMPLE.TXT contains information about the samples given for MASM for Windows NT. Both files include information about additional tools you may need to build some of the samples. If you choose to install the sample code during the setup process, both SAMPLES.TXT and NTSAMPLE.TXT are included. SAMPLES.TXT can be found in the \MASM611\SAMPLES subdirectory; NTSAMPLE.TXT can be found in the \MASM611\SAMPLES\NTSAMPLE subdirectory. Using Control-C to Halt Operation of MASM ----------------------------------------- MS-DOS applications running under DPMI, such as ML.EXE, may not respond immediately to pressing Control-C. If you press Control-C, and ^C appears on the screen but you are not returned to MS-DOS, press the Enter key. Using MASM 6.x Structures ------------------------- MASM 6.x supports a more powerful syntax for structure definition and usage than previous versions of MASM. This more powerful syntax is enabled by default. To use the older syntax, issue the OPTION OLDSTRUCTS directive (see Appendix A of the MASM Programmer's Guide for more information). Note: use of nested structures requires the new MASM 6.x syntax. If you use nested structures, the OPTION OLDSTRUCTS directive will be ignored for the structure which is nested. Visual C++ 1.0/Fortran PowerStation 1.0 Compatibility ----------------------------------------------------- There are specific steps you must take to use MASM 6.11 with Microsoft Visual C++ 1.0 or Microsoft Fortran PowerStation 1.0. If you wish to do mixed language programming with these products, it is recommended that: - You install Visual C++/Fortran PowerStation and MASM 6.11 in separate sub-directories. - You place \MSVC\BIN or \F32\BIN (your Visual C++ or Fortran PowerStation sub-directory) first on your path statement before \MASM611\BIN (your MASM 6.11 sub-directory). - You use NMAKE.EXE from MASM 6.11. You can do this using various methods, such as moving or renaming NMAKE.EXE installed in \MSVC or \F32 thus causing the system to continue searching your path and use the NMAKE.EXE in \MASM611. Optionally, for MASM 6.11/Visual C++ mixed programming, you may use NMAKER.EXE which is installed with both products. When using the LINK utility included with Visual C++ 1.0, you may encounter one or both of the following warnings: LINK : warning L4017: /r : unrecognized option name; option ignored CVPACK : warning CK4007 : unrecognized option /x; option ignored These warnings do not affect the resulting program and should be ignored. Working with MASM 5.1 Code -------------------------- MASM 6.x offers major advances over previous versions of MASM. Some of these improvements require changes that make MASM 5.1 source code incompatible with MASM 6.x. To provide compatibility with code written for MASM 5.1, MASM 6.x allows you to access MASM 5.1 compatibility code in three ways: - By using the conversion driver MASM.EXE. MASM.EXE converts your existing command-line options to the new syntax, adds the compatibility option /Zm, and invokes ML.EXE. - By using ML.EXE with the /Zm option. You also need to convert command-line options to the new syntax. - By placing the statement OPTION M510 at the beginning of each file. You also need to convert command-line options to the new syntax. In most cases, using the /Zm option or OPTION M510 will be the best solution for assembling existing code. If you prefer to modify your code so it can be assembled without /Zm or OPTION M510, do the following: 1. Add the appropriate OPTION directives to your code. - Always add the following: OPTION OLDSTRUCTS ; Supports old-style structures OPTION OLDMACROS ; Supports old-style macros OPTION DOTNAME ; Supports naming identifiers with ; a leading dot [.] - If your code does not specify the .386 or .386P directive, add the following: OPTION EXPR16 ; Use 16-bit precision in expressions - If your code does not contain a .MODEL directive, add the following: OPTION OFFSET:SEGMENT ; Specifies that the OFFSET operator ; defaults to segment-relative rather ; than group-relative - If your code does not contain a .MODEL directive or if the .MODEL directive does not specify a language, add the following: OPTION NOSCOPED ; Makes code labels global rather than ; local to the procedure in which they ; appear OPTION PROC:PRIVATE ; Makes code labels defined with PROC ; local unless specified otherwise 2. Once your code assembles with the OPTION directives, remove each OPTION directive, one at a time, and reassemble the code after you remove each one. Usually, it is best to remove the OPTION directives in the opposite order in which you added them. In some cases, you may decide that you prefer the MASM 5.x compatibility behavior instead of the new MASM 6.x behavior. When this is true, do not remove the corresponding OPTION statement from your code. For more information on assembling MASM 5.1 code, see Appendix A of the MASM Programmer's Guide. Working With Microsoft BASIC Far Strings --------------------------------------------- The BASIC runtime function StringAssign does not correctly handle strings of zero length. Instead of calling StringAssign to convert a zero-length string, simply return a near pointer to a doubleword with the value 0. ======================< Part 4: Known Assembler Bugs >==================== Exiting from MS-DOS Critical Errors -------------------------------------------------- MS-DOS critical errors, such as attempting to assemble a file on a drive which does not exist or is empty, produce the "Abort, Retry or Fail?" error message. Selecting "Abort" when running MASM in MS-DOS may cause memory to be corrupted. This problem does not occur when running MASM in Windows. To avoid this problem, select "Retry" or "Fail", as appropriate. Expression Order in High-Level Conditionals -------------------------------------------------- Comparisons in high-level conditionals cannot begin with a literal. For instance, this comparison causes an error: .IF 1 == AX but this works properly: .IF AX == 1 Hexadecimal Constants --------------------- In some instances, ML might not generate the appropriate error message if it encounters a hexadecimal constant that does not have an appending "h". The following will help to ensure that hexadecimal constants are properly represented: - Make sure that all hexadecimal constants have an appending "h". - Begin all hexadecimal constants with the numeral 0. This ensures that the compiler will generate the appropriate error message if it encounters a hexadecimal constant that does not end in "h". Initializing Nested Structures -------------------------------------------------- If one structure is nested within another, the inner structure's initializer list must either be empty or include a comma between every field. For example, the structure INFO declared on page 123 of the Programmer's Guide contains a structure of type DISKDRIVES, which in turn contains three BYTE fields. An object of type INFO could be initialized as: Info1 INFO { , , , , { }} ; Inner initializer list is blank or as: Info1 INFO { , , , , {1, 2, }} ; Commas for all three fields but not as: Info1 INFO { , , , , {1, 2 }} ; Error: missing last comma Intersegment Near Jumps in Flat Model ------------------------------------- Intersegment near jumps do not work across files (externs) in flat model. When programming in flat mode, make sure that all intersegment near jumps occur within the same file. Span-Dependent Expressions used in Macros -------------------------------------------------- MASM 6.1x evaluates macro expressions only on the first pass of assembly, but code and data are reevaluated on subsequent passes. Because of this, macro expressions which depend on the span between two addresses may not evaluate correctly. For instance, the following code will not evaluate correctly: Label1: JMP Label2 Label2: REPEAT Label2 - Label1 ; Evaluates incorrectly INC AX ENDM View the listing file to determine if a questionable macro expression was evaluated as desired. Span-Dependent Equates in Macros and EXTERNDEF ABS --------------------------------------------------- The ABS operator causes an identifier to be exported as a relocatable unsized constant (see Programmer's Guide page 220). If ABS is used with EXTERNDEF within a macro, and the constant being exported depends on the difference between two addresses, the constant may not be exported correctly. In some cases, the listing file will show the correct value, but the value in the resulting .obj will be incorrect. For instance, the following code will not evaluate correctly: EXTERNDEF TableSize:ABS ; Will not be exported correctly MAKETABLE MACRO Table1 LABEL BYTE DB 0, 1, 2 TableSize EQU $-Table1 ENDM SEG1 SEGMENT MAKETABLE SEG1 ENDS To avoid this problem, either use the 'PUBLIC' directive in place of 'EXTERNDEF', or put a label before the equate, within the macro. Span-Dependent Text Equates -------------------------------------------------- The TEXTEQU operator is evaluated on the first assembly pass. If TEXTEQU is used with an expression that depends on the difference between two addresses, the resulting constant may be incorrect. For instance, the following code will not evaluate correctly: Label1: JMP Label2 Label2: WrongNum TEXTEQU %Label2-Label1 ; WrongNum will be incorrect STRUCT and RECORD Initialization -------------------------------- If a STRUCT containing a UNION is initialized incorrectly, it is possible that the compiler might not generate an appropriate error. If the UNION contains a RECORD, the STRUCT is initialized to the default value for the original UNION. Using The /link /nologo Command Line Options --------------------------------------------------------- The /link command line option for ML causes all following parameters to be passed to the linker. If the /nologo command line option is passed to the linker, the linker may parse other parameters incorrectly. To avoid this problem, use the /nologo command line switch for ML rather than passing it to the linker. For instance, replace: ML hello.asm /link /nologo MYLIB.LIB with: ML /nologo hello.asm /link MYLIB.LIB Alternately, you may use the NMAKE utility to automate building your project.